Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/deploy.yaml:
- Line 38: The comment on the deploy workflow is inconsistent: update the
comment that currently reads "Runtime UAT toggle: add PR label 'run-staging' to
enable UAT on PRs into main." so it references "run-staging" terminology; change
the phrase "Runtime UAT toggle" to language that matches the label (e.g.,
"Runtime staging toggle") so the comment aligns with the `run-staging` label and
the purpose described in the workflow.

In `@docs/planning/request_to_token_attribution.md`:
- Around line 210-215: The acceptance table incorrectly marks "100% include
workflow + stage" and "Support KQL joins by operation_Id/request_id" as ✅ Done
while downstream tasks show dependencies still outstanding; update the table
rows for "100% include workflow + stage" and "Support KQL joins by
operation_Id/request_id" to reflect the real state by either (A) changing the
Status cell to "🔜 Ready" or "⏳ In Progress" until cognitive-mesh begins passing
correlation metadata and pvc-costops-analytics finishes KQL queries, or (B)
rewording the criterion label to "Capability Available: workflow+stage metadata"
/ "Capability Available: KQL join support" to distinguish capability from
feature completion; ensure you reference the dependency names cognitive-mesh and
pvc-costops-analytics in the Notes column so the relationship is clear.

---

Outside diff comments:
In `@docs/PRD.md`:
- Line 170: Replace the remaining "Dev/UAT/Prod" phrasing in the acceptance
criteria with the consistent "Dev/staging/Prod" term (specifically update the
item containing "Dev/UAT/Prod" to "Dev/staging/Prod"); also scan the PRD.md for
any other occurrences of "UAT" or "UAT→staging" and update them to "staging" so
the document uses a single environment name consistently.
- Line 183: The milestone text "M2: UAT + Prod; environment approvals." is
inconsistent with the rest of the doc that uses "staging"—update the M2
milestone (look for the "M2" milestone heading/text) to read "M2: staging +
Prod; environment approvals." and scan for any other lingering "UAT" references
to replace them with "staging" to maintain consistency.

In `@README.md`:
- Line 107: Update the README line that reads "[CI/CD Runbook](docs/CI_CD.md) –
workflow behavior, UAT toggle, smoke tests" to use the new terminology "staging"
instead of "UAT" (e.g., "...workflow behavior, staging toggle, smoke tests") so
it matches the rest of the PR; ensure the phrase appears exactly in the README
and the linked docs if there are other occurrences of "UAT" to rename
consistently.

---

Nitpick comments:
In `@docs/planning/request_to_token_attribution.md`:
- Around line 219-221: Change the tense for the infra dependency line "infra:
Application Insights added for trace storage" to present/future tense to reflect
that this PR is adding it; for example update the list item to "infra:
Application Insights being added for trace storage" or "infra: Requires
Application Insights for trace storage" so the dependency wording is consistent
with the other lines like "cognitive-mesh: Must pass correlation metadata to
gateway" and "pvc-costops-analytics: Must create KQL queries for new event
shape".

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/planning/request_to_token_attribution.md`:
- Around line 233-235: The doc uses two conflicting phrases — "pass correlation
metadata in request body" and "must pass correlation headers" — causing
ambiguity; choose one canonical requirement (preferably "pass correlation
metadata in request body") and update every occurrence of the other phrase so
the integration requirement for cognitive-mesh is consistent, including the
pending item line that currently lists "Pass correlation metadata in request
body" and the earlier sentence that currently reads "must pass correlation
headers", plus any related sections or examples that describe the required
integration mode (search for those exact strings to find and replace).
- Line 221: Replace the claim "Application Insights being added for trace
storage" with the clarified sentence: "Application Insights resource +
connection string wiring added; actual trace export requires custom LiteLLM
image deployment or explicit OTLP collector configuration." Also ensure the note
references the existing symbols/vars: APPLICATIONINSIGHTS_CONNECTION_STRING, the
comment about the custom LiteLLM image including azure-monitor-opentelemetry,
and the default empty OTEL_EXPORTER_OTLP_ENDPOINT so readers see that trace
export is not yet operational without those pieces.

---

Nitpick comments:
In @.github/workflows/deploy.yaml:
- Around line 327-338: The deploy-staging job duplicates logic present in
deploy-dev/deploy-prod; extract the shared steps (quickcheck, login,
init/plan/apply, smoke tests) into a reusable workflow or composite action and
call it from the deploy-staging, deploy-dev, and deploy-prod jobs; create a new
reusable workflow/composite (e.g., deploy-workflow or deploy-composite) that
accepts inputs like TF_VAR_env and PR label conditions, move the common run
steps there, and update the deploy-staging job (and the other deploy-* jobs) to
invoke that reusable workflow via uses: or workflow_call so only
environment-specific conditionals (name, environment, env.TF_VAR_env, if
condition) remain in each job.

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/architecture/README.md`:
- Around line 30-75: The fenced ASCII diagrams (the blocks containing "SLM" / "↓
confidence high" / "Return result", the "Router (SLM)" block with "Code model"
etc., the "Device" block with "SLM" and "embeddings", and the "User Request" ->
"Router (SLM)" diagram) need explicit language specifiers for markdown linting;
update each triple-backtick fence that currently starts with ``` to use ```text
(e.g., change ``` to ```text) for the Cascade Architecture ("SLM"/"↓ confidence
high"), Router + Specialists ("Router (SLM)"), Local-First AI ("Device"), and
Typical Modern AI Stack ("User Request"/"Router (SLM)") blocks so linters accept
the files.

In `@docs/guides/README.md`:
- Line 68: Replace the sentence "In many cases an SLM + RAG outperforms a large
model with no context." with a tighter phrasing using an alternative to "In many
cases" (e.g., "Often, an SLM + RAG outperforms a large model with no context."
or "Frequently, an SLM + RAG outperforms a large model with no context."),
preserving the "SLM + RAG" wording and punctuation; ensure spacing and comma
after the adverb are correct and that the rest of the sentence remains
unchanged.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/architecture/02-container-architecture.md`:
- Around line 19-20: The diagram declares the node C3[GitHub Webhooks] but never
connects it into the flow; add an edge from C3 to the appropriate downstream
node (e.g., CodeFlow or whichever node represents ingress/CI processing) so the
webhook is part of the flow. Update the same missing connections in the later
block (the repeated section around lines 58-83) so both occurrences of C3 are
connected (for example: C3 --> CodeFlow or C3 --> <IngressNodeName>), ensuring
the diagram reflects actual webhook ingress behavior.

In `@docs/architecture/04-observability-telemetry.md`:
- Around line 35-39: The Ingest subgraph is missing Prometheus as a telemetry
destination; update the diagram block (the Ingest subgraph containing
I1/OpenTelemetry, I2/Azure Monitor, I3/Blob Export) to add a fourth node for
Prometheus (e.g., I4[Prometheus]) and add the flow from the application metrics
endpoint (/metrics) into that node; also update the surrounding text to mention
that LiteLLM enables Prometheus callbacks (success_callback/failure_callback
include "prometheus") and reference the
infra/modules/aigateway_aca/main.tf:95-113 behavior so readers know Prometheus
is a primary telemetry sink alongside OTEL, Azure Monitor and Blob Export.

In `@docs/architecture/reference/matrix-gateway.md`:
- Around line 91-95: Replace the inconsistent confidence threshold text so the
doc uses the same policy values from the gateway SLM guide (0.90 / 0.75): update
the table row currently reading "confidence < 0.70" to the correct boundary
(e.g., "confidence < 0.75"), and ensure all other mentions of confidence-based
routing (the lines referencing escalation to LLM or fallback behavior) use the
0.90 / 0.75 thresholds consistently.
- Around line 42-52: The example response JSON does not match the declared
contract type ClassifyRequestOutput; update the example payload to use the
contract's field names (label and recommended_tier) and remove or rename
intent/recommended_target/recommended_model_tier accordingly so the example
reflects ClassifyRequestOutput's shape; ensure any referenced values (e.g.,
target engine or tier) are mapped into recommended_tier or documented separately
and apply the same fix to the other example block at lines 57-74.

In `@docs/architecture/reference/matrix-rooivalk.md`:
- Around line 110-113: The DEFAULT_THRESHOLDS constant contains
sop_suggestion.direct_suggest set to 0.78 which conflicts with the documented
threshold table stating top-tier behavior is >= 0.80; update the
DEFAULT_THRESHOLDS (symbol DEFAULT_THRESHOLDS) entry for
sop_suggestion.direct_suggest to 0.80 and verify any other related keys
(operator_summary, sop_suggestion.manual_lookup) and the summary table values
are consistent so the code constant and documentation table match.
- Around line 27-44: The fenced safety ASCII-art block in matrix-rooivalk.md is
unlabeled, triggering MD040; update the block fence to include a language hint
(e.g., add "text" after the opening ```) so the safety boundary block becomes a
labeled fenced code block and stops triggering the lint rule while preserving
the ASCII-art content.

In `@docs/architecture/reference/slm-management-plan.md`:
- Around line 43-56: The Markdown file contains unlabeled fenced code blocks
(e.g., the "Cost Control Layers" ASCII-art block, the "Request" ASCII-art block,
and the "Discovery → Testing → Staging → Production → Deprecated → Retired"
block) which trigger MD040; update each fenced block by adding a language label
(use "text") to the opening triple-backticks so the blocks become fenced with
```text to satisfy markdown linting and ensure consistent rendering.
- Around line 266-274: The checklist contains a duplicate/completed item "Add
explicit safety boundary for PhoenixRooivalk" in the tail checklist; remove that
line or change it to a follow-up task (e.g., "Verify existing PhoenixRooivalk
safety boundary and close gaps") so it does not appear as an unchecked action;
check for and reconcile with the existing safety-boundary entries already
documented in the earlier "safety boundary" section and the other mention so the
checklist reflects only outstanding work.

In `@docs/architecture/systems/agentkit-forge.md`:
- Around line 7-24: The code block in the architecture diagram is missing a
fence language which triggers markdownlint MD040; update the opening
triple-backtick for the ASCII diagram to include a language (e.g., change ``` to
```text or ```mermaid if you convert to mermaid) so the fenced block around the
diagram (the block that begins with the three backticks and contains "Agent Task
│ ▼ ... └─→ LLM Synthesis") specifies a language and satisfies the linter.

In `@docs/architecture/systems/codeflow-engine.md`:
- Around line 7-24: The fenced architecture diagram block is missing a language
tag; update the triple-backtick fence that opens the diagram (the ASCII flow
block shown under "Git Push / PR Event") to use the language identifier `text`
(i.e., change ``` to ```text) so markdownlint MD040 is satisfied while
preserving the diagram content.
- Around line 94-100: The f-string assigned to variable prompt embeds literal
JSON braces which must be escaped; in the prompt construction (variable prompt
using change_type and impacted_files) double the outer curly braces around the
JSON-like object (e.g., replace { "run_unit": ... } with {{ "run_unit": ... }})
so Python treats them as literal braces in the f-string rather than expression
delimiters.

In `@docs/architecture/systems/cognitive-mesh.md`:
- Around line 7-29: The fenced ASCII diagram block starting with ``` should
include a language identifier to satisfy markdown lint MD040; edit the block
that begins with the triple backticks before "User Query" and change it to start
with ```text so the diagram (the SLM Control Fabric / Routing Decision / Code
Agent / Research Agent section) is fenced as ```text.

---

Nitpick comments:
In `@docs/architecture/04-observability-telemetry.md`:
- Line 37: The doc uses "Azure Monitor" generically (see node label I2[Azure
Monitor]); update wording to specifically say "Application Insights" where the
deployed resource and OTEL exporter target Application Insights, or add a
clarifying note that Application Insights is the Azure Monitor implementation
used and that the OTEL exporter uses the APPLICATIONINSIGHTS_CONNECTION_STRING
env var; ensure references to the OTEL exporter and the environment variable
(APPLICATIONINSIGHTS_CONNECTION_STRING) and the infrastructure intent (OTEL ->
Application Insights) are explicit.
- Around line 1-94: Add a short "Retention policies" subsection under "Telemetry
Architecture" documenting the Application Insights retention defaults used by
the infra: production retention 90 days and non-production retention 30 days,
note that these are environment-specific and where operators should look to
change them (the Application Insights resource configuration), and recommend
including this retention info in operational runbooks so observability operators
can align expectations and costs; reference the "Application Insights" resource
and the "Telemetry Architecture" section to locate where to add the note.

In `@docs/architecture/reference/slm-implementation-matrix.md`:
- Around line 18-27: The fenced code block in slm-implementation-matrix.md lacks
a language specifier which tools rely on for proper rendering; update the
opening fence for the directory tree in the file (the block starting with ```)
to include a language label such as text or plaintext so it reads e.g. ```text,
ensuring the directory structure snippet renders correctly.
- Around line 254-260: The fenced code block containing the fallback pattern
list should include a language specifier so syntax highlighters render it as
plain text; update the triple-backtick fence around the list (the block starting
with "1. SLM timeout → Deterministic rules") to use a language like "text" or
"plaintext" (e.g., ```text) and keep the content unchanged.

In `@docs/architecture/reference/strategic/07-deployment-model.md`:
- Around line 29-34: Update the CodeFlow "Best SLM Jobs" cell to use the more
specific terminology used across sibling docs: replace the phrase "PR triage,
log analysis" in the CodeFlow table row with targeted terms such as "PR
classification, CI failure triage, release-note extraction" so the matrix aligns
with other references and reduces ambiguity when searching for CodeFlow
capabilities.

In `@docs/architecture/systems/ai-gateway.md`:
- Around line 7-24: The fenced ASCII diagram block in ai-gateway.md is missing a
language specifier; update the opening triple-backtick that precedes the diagram
(the block containing "Client Request" and "SLM Control Layer") to include a
language tag such as text or plaintext (e.g., change ``` to ```text) so the
diagram satisfies markdown linting rules and is treated as plain text.
- Around line 1-146: The docs miss explicit v1 API routing rules; update the
architecture doc to state that incoming /v1/responses and /v1/embeddings
requests must be routed to Azure OpenAI via the LiteLLM provider. Edit the
"Routing Logic" section (update gateway_admission and/or add a short
route_to_provider example) to show mapping of those endpoints to Azure
OpenAI/LiteLLM, add a note in the "Implementation Checklist" to configure
LiteLLM Azure provider for those endpoints, and include a short example/rule
describing any differences in handling responses vs embeddings (e.g., batching,
model selection).

In `@docs/architecture/systems/cognitive-mesh.md`:
- Line 146: Update the tradeoff table entry that currently reads "Very large
token savings" to "Large token savings" to tighten wording; locate the table row
containing the phrase "Very large token savings | Decomposition quality can
bottleneck workflow" in cognitive-mesh.md and replace the left-side cell text
only, leaving the rest of the row unchanged.

In `@docs/architecture/systems/phoenix-rooivalk.md`:
- Around line 7-27: The fenced ASCII diagram currently lacks a language
specifier; update the Markdown fenced code block that surrounds the ASCII
architecture diagram (the block starting with ``` and containing "Sensors",
"Rules + Signal Models + Fusion", "SLM Interpretation Layer", etc.) to include a
language tag (e.g., add `text` after the opening backticks as ```text) so
markdown linting rules are satisfied.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/deploy-environment.yaml:
- Around line 53-66: The reusable workflow currently only sets a subset of env
vars (TF_VAR_azure_openai_*, TF_VAR_gateway_key, TF_VAR_codex_*, etc.), causing
caller-level
secrets/TF_BACKEND_*/AZURE_CLIENT_ID/AZURE_TENANT_ID/AZURE_SUBSCRIPTION_ID,
EXPECTED_AOAI_ENDPOINT_HOST and TF_VAR_state_service_container_image to be empty
at apply time and breaking guards; update the env block to explicitly pass all
required variables from inputs/secrets (including AZURE_CLIENT_ID,
AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID, TF_BACKEND_*,
TF_VAR_state_service_container_image, EXPECTED_AOAI_ENDPOINT_HOST and any other
Terraform TF_VAR_* the plan relies on) so plan and apply see the same inputs,
and replace the invalid GitHub Actions function syntax if(inputs.env_name ==
'prod', '3', '1') with the supported ternary-like expression inputs.env_name ==
'prod' && '3' || '1' to restore the Line 211 value evaluation and ensure the
prod AOAI guard and Line 215 smoke gate run as intended.
- Line 211: The models_wait_attempts assignment uses the unsupported if()
expression; update the expression for models_wait_attempts to use GitHub
Actions' case() function to select '3' when inputs.env_name == 'prod' otherwise
'1' (reference the models_wait_attempts key in the deploy-environment workflow);
ensure the case() expression compares inputs.env_name to 'prod' and returns the
correct string values, or alternatively use the safe conditional pattern
(condition && value1 || value2) only if value1 cannot be falsy.

In @.github/workflows/deploy.yaml:
- Around line 154-170: The job-level environment key must be removed from the
reusable-workflow caller jobs (e.g., deploy-dev, deploy-staging, deploy-prod)
because jobs that use `uses:` cannot include `environment:`; update each caller
to only pass the env via the `env_name` input (already present) and then add
`environment: ${{ inputs.env_name }}` inside the called workflow
`deploy-environment.yaml` (use the `inputs.env_name` value in that workflow's
job definition) so the environment selection is handled by the reusable workflow
rather than the callers.

In `@docs/planning/request_to_token_attribution.md`:
- Line 221: The doc and Terraform behavior conflict because a new Terraform
output application_insights_connection_string exposes a secret while the policy
mandates routing secrets through Key Vault and never outputting them; either
remove the Terraform output or mark it as sensitive and change the deployment to
store the connection string in Key Vault (and update any consumers to read from
Key Vault), then update this doc (and the related note at lines ~229) to state
the chosen approach (no outputs for secrets or sensitive output with Key
Vault-backed handling) and reference the application_insights_connection_string
symbol and Key Vault usage so readers know how to retrieve the secret securely.

---

Duplicate comments:
In `@docs/planning/request_to_token_attribution.md`:
- Around line 125-155: Change the ambiguous "Required:" label to clearly
indicate that request-body metadata is the recommended/default integration
(e.g., replace "Required:" with "Recommended/Preferred") and add one sentence
after "Method B: Via HTTP Headers" stating that headers are an alternative
option that requires additional LiteLLM configuration or middleware; reference
the existing headings "Method A: Via Request Metadata (Recommended)" and "Method
B: Via HTTP Headers" so the reader knows which sections to update.